home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
351-375
/
disk_374
/
mat
/
mat.doc
< prev
next >
Wrap
Text File
|
1992-05-06
|
52KB
|
1,201 lines
============================================================================
|| ||
|| MAT -- p.n.; poss. abbrev. of "Match"; also "Matte" [Motion ||
|| Picture Arts]: means of cutting, inserting and superposing ||
|| disparate items. ||
|| ||
|| ------------------- ||
|| ||
|| This program provides a flexible string-searching, pattern-matching ||
|| and substitution mechanism for both text and filenames. Searching ||
|| for a string in a file is fast (it can be three times as fast as the ||
|| AmigaDOS 'SEARCH'). The (much slower) matching scheme is an extended ||
|| version of the standard AmigaDOS pattern-matching convention, with ||
|| the added features of negation and "slicing" of matched strings. It ||
|| will probably be most useful within command (or ARexx) scripts to ||
|| extend the operations possible with AmigaDOS. ||
|| ||
|| ||
|| ||
|| * Searches for strings or patterns within text files. ||
|| ||
|| * Rearranges text within matched lines to ||
|| create new files. ||
|| ||
|| * Tags and labels can be added to the output stream ||
|| at desired points ||
|| ||
|| * Searches directories for matching file names. ||
|| ||
|| * Creates Command Script Files by inserting the whole or ||
|| parts of matched filenames into text templates. ||
|| ||
|| * Control commands for the program may be read from a ||
|| script file as well as the command line. ||
|| ||
|| ||
|| -- Copyright 1990 Peter J. Goodeve -- ||
============================================================================
-- by Pete Goodeve --
July 1990
Overview
________
This program is intended to fill a number of pattern matching needs
not covered by other facilities. It is very flexible, and consequently
has a number of features you may never use, but it is well suited to those
everyday jobs, too.
It handles both string searches (in which the string will be found anywhere
it occurs on the lines being scanned), and pattern matches that compare
each whole line against a pattern. String searches can be at least three
times as fast as if you used the AmigaDOS 'SEARCH' (disk access time may
well limit the improvement, though). Pattern matches are much slower of
course, but provide much more precise control of the operation. You can
also often get the best of both by "filtering" the text first with a string
search and applying the pattern only to those lines that contain the filter
string.
Patterns are in the usual AmigaDOS format (as used by LIST and so on), with
a number of extensions. You can specify "negative match" segments, whose
appearance will cause a match to fail, and you can -- most importantly --
indicate "slice points" that mark pieces of the matched string to be
rearranged in the output.
To illustrate:
MAT S #include mysrc.c
would print out all lines that contain the string "#include" in the
file "mysrc.c". Note that a) the keyword argument "S" signals that
this is a string search (you can also use the full keyword "SEARCH"
-- upper or lower case); b) the string can be anywhere in the line
(though this particular one will usually be at the beginning);
and c) the character '#' has no special meaning in a string search
(as opposed to being a special character in a pattern).
MAT S #include #?.c
would do the same thing for all files in the current directory ending
in ".c". You can have several file specifications in one command
if you like:
MAT S #include test/#?.c WORK:#?/#?.c
would search all such files in the subdirectory "test" and all
(immediate) subdirectories of assigned device "WORK:".
The preceding examples simply display all lines that fit the criterion,
but you can add a "template" to specify exactly what should be output.
MAT S #include T "^F line ^N: ^O" #?.c
Here, the addition of the template, with its preceding keyword "T"
(or full word "TEMPLATE"), specifies that each matching line should
be displayed in this fashion:
"mysrc.c line 5: #include <stdio.h>"
The marker "^F" (two characters -- the caret '^' followed by upper
case 'F' -- NOT a "control-F") indicates that the current file name
should appear here; "^N" represents the current line number, and
"^O" ("Oh", not "zero") indicates the original current line.
There are a number of other template markers you can use, especially
when you are matching against a "slicing pattern" rather than doing a
string search. You can also specify a template for all the lines that
FAIL to match.
In addition to templates, which apply to every line, you can supply
a "Tag", which applies once per file -- immediately before the first
matched line if there is one, otherwise when the whole file has been
read (giving an alternative message). The format is the same as a
template.
MAT S #include TAG "^F:^| No matches found in ^F" #?.c
will display the filename (once) before all lines matched in that
file, or, if there were no matches, report that fact. The "^|"
pair separates the 'success' and 'failure' portions of the tag
(or template).
Pattern matching can be done on the lines of a file in much the same way.
MAT "#?printf#?,# X,#?" mysrc.c
looks for any lines that do a "printf" on variable "X" (with
arbitrary characters intervening. (Notice that no keyword is
needed here, as this is the default case, but if you prefer you
can use the key "P" or "PAT"; for variant forms, or where there
is ambiguity, a keyword may be required.)
You can speed things up by screening the lines first:
MAT S printf P "#?printf#?,# X,#?" mysrc.c
only does the full match on lines that contain printf. The keyword
"P" is needed here to make your intention clear.
You can add "slice-marks" to a pattern, and rearrange the resulting pieces
with a template. The slice-mark is a single caret character placed at the
desired point. (When you use slice marks, you must also use a template.)
MAT #?^(word|another)^#? "^1: ^0----^2" myfile
Here slice marks are placed either side of the bracketed alternation
in the pattern. In the template,"^0" is the segment of the line matched
by the part of the pattern before the first slice mark, "^1" is the
segment between the two marks (i.e. "word" or "another", depending on
which was matched), and "^2" is the rest of the line. Thus, if the
input line was
"this line contains the word we are looking for"
the output would be
"word: this line contains the ---- we are looking for"
Up to this point, the examples have focussed on scanning text files,
but the same mechanisms can equally well examine directories. For the
simple jobs, of course, one would just do a DIR or LIST, or perhaps a
LIST...LFORMAT.., but Mat can do a few things that the others can't.
For instance, the ability to exclude files by means of a "negative
match" can be very useful. Also the template is rather more flexible
than that of "LIST..LFORMAT (and pre-dates it by about three years!),
among other things allowing specifiers for directory-path separate
from the filename.
For example, for taking quick looks at a bunch of files, I have a
script that does something like this (although in fact it also
pops up a new full-screen window to do it in, and uses a PIPE:):
.K filepat/A
MAT >T:_mm T "more ^P" F <filepat>
execute T:_mm
"^P" represents a complete pathname, and the keyword "F" (or "FILES")
says that the file names (specified in the filepat argument) are to be
used themselves, rather than be scanned.
The preceding example is similar to the "DPAT" script that comes with
1.3, but you can do other things, too. Suppose (and I have actually
been in this situation) that I have a bunch of files that I have
previously renamed to "myfile.c_0", "myfile.o_0", "myfile_0" and so
on, which I now want to restore to their former names by chopping off
th "_0". I have a script that calls Mat in a similar way to the
above, and does just what I want:
REN myfile#?^_0 AS ^0
The first argument to the script is a pattern to select the files
to be renamed, and the second is the template specification of the
new names. Notice the "slice-mark" '^' in the pattern, and the
marker "^0" (meaning the part to the left of the slice) in the
template. Without bothering to detail the script, the core is a
Mat command line that creates appropriate "RENAME" commands to be
executed.
In most cases you will want to have Mat embedded in script files, as this
can drastically simplify the otherwise sometimes complex syntax. Mat, by
the way, returns a "WARN" value (5) to AmigaDOS if no match was found --
useful for conditional execution in scripts.
This has only been a brief sketch of the various modes and so on that the
program has. It is worth bearing in mind though that it has a number of
features -- including the possibility of accepting commands from a script
file or pipe -- that add to its usefulness in things like installation
scripts. These features also let it work well with ARexx (even though it
doesn't itself have an ARexx port).
The following sections go into more detail about Mat's capabilities.
First the command line formats and operating modes are described, then
the keywords are listed in detail. Following this is a full description
of AmigaDOS-type patterns in general, and the extensions used in Mat.
Finally comes a discussion of Templates and File Specifiers.
+ + + + +
Installation and Operation
__________________________
Mat is like any other CLI/Shell command, and is invoked by a command line
with suitable arguments. For normal use it should be available in the
C: directory (or at least on the path of the current shell). For added
speed (under AmigaDOS 1.3 or later) it may be made Resident.
Command Line Arguments
______________________
There are a number of basic command forms corresponding to the various
operations Mat can perform. Each of these in turn can have variants,
and they can often be combined to achieve a particular result. There
are several common basic components, however, which first need clear
understanding.
In the order they normally appear in the command line, from left to
right, they are: <Search-String>, <Pattern>, <Template>, and <Name-Spec>.
Only the last of these is invariably present; the other three MAY all
appear, but quite usually don't. Keywords precede each where necessary
to identify them, and other keywords may be interspersed to give
further control.
<Search-String>: A literal string of characters that will be searched
for in a text file. Any line that contains the string
as a substring is considered to match. No characters in the string
will get special treatment -- there are no "wild-cards" or such.
Matches must be exact, with upper and lower case distinct, unless the
NOCASE keyword is used. Search-Strings are only used in text searches,
not in filename or key matching. A Search-String must be identified by
the required keyword "SEARCH" or its abbreviation "S".
<Pattern>: An AmigaDOS-type pattern specifier string, usually
containing "pattern-structuring" characters with
special meaning. (See the section on "Pattern Matching" later.) It is
always matched against the whole target of concern (a line of text,
filename, or argument). Again, case is relevant unless NOCASE is used.
If a pattern is the first argument on the command line it does not need
a keyword (as it is the default) but if it is elsewhere -- following a
Search-String for example -- it must be preceded by "PAT" or "P". (You
would also have use the keyword in the remotely possible case that the
pattern was itself identical to another keyword.)
<Template>: A string, usually containing "template markers",
that directs the program as to the output it is to
generate for each matching -- and possibly non-matching item. (See the
section on "Templates".) If it is absent, the output depends on the
mode: during a text search each matching target is simply output in its
entirety; when matching filenames or keys there is no output at all
without a template. If a Template string immediately follows an
initial Pattern argument that REQUIRES a template (i.e. it has
slice-marks), no keyword is needed, but it is probably best to use one
anyway; it is of course "TEMPLATE" or just "T".
<Name-Spec>: Either a simple string or a pattern that defines
the entities to be examined. There may be several on
one command line. In the Text-Searching modes, it indicates a file or
group of files to be scanned (referred to as a <File-Spec> below). For
Directory Searching, it will normally be the actual search pattern to
match. It may also represent a "key" (such as a command script
argument) that is to be tested directly against a Pattern. There is no
specific associated keyword, but preceding mode-selection arguments may
determine the meaning. For searching text files, no keyword is usually
needed, as this is the default, but you may occasionally have to supply
one to prevent ambiguity (a file name the same as a keyword, for
example); if you do, the word is "FROM". To select Directory
Searching, you use one of: "FILES" (or "F") -- to search only for files
(not directories) --; "DIRS" ("D") -- to retrieve only directory names
that match --; or "NAMES" ("N") -- to match both. To match the
arguments themselves use "KEY" ("K").
Not all keywords have abbreviations by the way -- only some of the
frequent, non-ambiguous ones. All may be given in upper or lower case,
however. If any of the above items have embedded spaces, they must of
course be enclosed in quotes (which will be stripped off before they
are used).
Operating Modes
_______________
Text Search:
The default function of Mat is to search text files for lines that
match a pattern:
MAT <Pattern> <Name-Spec>...
All lines that match are written to standard output (the screen,
normally). For details on patterns, including the Mat extensions and
the possibilities of "slicing" the matched string for use by a
template, see the section on "Pattern Matching".
To perform a string search rather than a pattern match, the form is:
MAT SEARCH <Search-String> <Name-Spec>...
or
MAT S <Search-String> <Name-Spec>...
You can also combine string search and pattern match:
MAT S <Search-String> P <Pattern> <Name-Spec>...
If both a Search-String and a Pattern are specified in the command
line, each line of the text file will be tested for the presence of the
string first, and only if that succeeds will the pattern be applied.
In situations where this can be done, pattern matching is hardly slower
than the string search alone.
With the above forms, you can control the text output with a template
(see the section on "Templates" for full details):
MAT <Pattern> TEMPLATE <Template> <Name-Spec>...
MAT <Pattern> T <Template> <Name-Spec>...
MAT S <Search-String> T <Template> <Name-Spec>...
In the particular case where a pattern has slice marks (see "Pattern
Matching"), and therefore requires a template, the keyword is optional
-- provided that the template argument is in the correct place:
MAT <Slice-Pattern> <Template> <Name-Spec>...
Directory Search:
When searching directories for matching names, a template is normally
expected:
MAT NAMES <Template> <Name-Spec>...
MAT NAMES T <Template> <Name-Spec>...
MAT N T <Template> <Name-Spec>...
The "TEMPLATE" keyword is optional with this precise form, but required
for others. For example, a separate pattern (in addition to the one in
the Name-Spec) is sometimes useful (to further subdivide the set of
found files for template formatting):
MAT <Pattern> T <Template> NAMES <Name-Spec>...
The template itself however is not optional. If you really want no
template (so nothing will be sent to the output for matches, you must
specify it as a null string; for example:
MAT NAMES "" <Name-Spec>...
The NAMES form locates all matching entries, both file and directory.
The equivalent forms to find just one or the other are:
MAT FILES <Template> <Name-Spec>...
MAT F <Template> <Name-Spec>...
MAT DIRS <Template> <Name-Spec>...
MAT D <Template> <Name-Spec>...
Other Modes:
You can check the arguments in the command line -- probably themselves
supplied as arguments to an execute script -- against a pattern:
MAT <Pattern> KEY <Name-Spec>...
MAT <Pattern> K <Name-Spec>...
Without a template, the KEY form simply checks for a match, and returns
WARN to AmigaDOS if it doesn't find one. No output is generated. Add
a template to get the desired output:
MAT <Pattern> K T <Template> <Name-Spec>...
A final mode simply writes all files that match the Name-Spec to
standard output in sequence. No processing of the files is done --
they needn't even be text:
MAT JOIN <Name-Spec>...
You can however supply a Tag-template (see sections on "Keywords" and
"Templates") that will be output for each file. The 'success' portion
will be written BEFORE the file, the 'fail' part AFTER it; either part
may be omitted. Labels are also valid in a JOIN command line.
Value returned to the CLI:
_________________________
When Mat returns to the CLI or Shell, it passes back a value of zero if
it has found at least one match. If it has found no matches at all it
returns a "WARN" value of 5. This happens in all modes, and can be
tested within a command script to see if the intended operation has
been successful. If you should just want to know if a match exists,
without needing to see any output, you can simply redirect this to
NIL:.
If Mat encounters an error which prevents it from continuing, like an
incorrectly formed pattern, it will return at once with an error code
of 20.
Keywords:
________
Aside from the mode selecting keywords discussed above, there are
a number used to control other features. Some of these take arguments
("SEARCH", "PAT", and "TEMPLATE" being examples we've already met).
In general, keywords can be placed either at the beginning of the line,
or at any appropriate later point, as long as they don't separate a
keyword and its argument. The exact effect may depend on where on the
command line they are placed; in many situations you could have several
interspersed along the line. Mat always processes the command arguments
in sequence, from left to right (unlike the position independent
keywords of AmigaDOS commands). All keywords may be in upper or lower
case. When so specified, they may be abbreviated to their first letter.
To summarize the mode selection keywords already mentioned:
FILES -- searches for matching filenames
DIRS -- searches for matching directory names
NAMES -- searches for both files and directories
KEY -- checks the command line for matches
JOIN -- sequentially copies all matching files to the output
All the above may be abbreviated to their first letter.
You may change modes within a command line if for some reason you need
to. The change takes place at the point the keyword is encountered.
These component specifiers have also been mentioned:
FROM <Name-Spec> -- sets text search mode and specifies
that the following argument is a Name-Spec
(No abbreviation). Rarely needed.
SEARCH <Search-String>
-- declares its argument to be a string
for quick scanning of following text files
(abbreviation "S").
PAT <Pattern> -- specifies that its following argument
is a pattern (abbreviation "P").
TEMPLATE <Template> -- specifies that its following argument
is a template (abbreviation "T"). The
template string may be null ("") to cancel
any previous template, or satisfy the
Directory Search's requirement for one.
Only one Search-String, one Pattern and one Template may be active
at any time. You can change any of them at any point in the command
line, though, replacing the old ones.
There are two other keywords that also take a template form argument:
TAG <Template> -- defines a "tag" (for text file modes only)
that will be output at most once for each file.
The 'success' portion of the template (see the "Templates" section)
will be output immediately before the first match found in the file;
the 'failure' part will be output if no match is found by the end
of the file. Note that this applies even if non-matching lines
are being output (by a 'fail' part of the line template)! Non
matching lines before the first match will also appear BEFORE
the tag. Some of the selectors that are available for a line
template (such as slices) are not so appropriate within a tag
template; they will be ignored if used. Declaring a new tag
replaces any previous one; only one may be active at a time.
LABEL <Template> -- outputs a "label" at the point it is
encountered in the command line. There
are the same restrictions on available template selectors as for
tags. If no "fail" part is supplied, the label will be output
unconditionally; if you do supply a fail part (after "^|"), the
"success" part preceding the divider will only be output if there
has been at least one match to that point, otherwise the fail
part will be output.
No abbreviations are provided for either of the previous or any of the
remaining keywords.
The following subsidiary mode controls can be put anywhere appropriate
on the command line:
NOCASE -- causes all subsequent searches to ignore the case of
pattern and text characters. It can be put anywhere in
the command line subject to the above restrictions; file specifiers
appearing before it will not be affected.
CASE -- cancels the effect of a previous NOCASE.
FIRST -- is only appropriate in text matching modes. It
causes the search of each file after it on the command
line to terminate when the first match is found. It is useful when
you just want to determine which files contain a pattern, rather
than listing every occurrence. It is compatible with templates and
other options.
ALL -- reverses the effect of FIRST if you should need to
do so within a command line.
NOLINES -- prevents the usual newline character being output
after each match. All subsequent matches will be shown
on the same line unless the template dictates otherwise. Don't
forget that you will usually want some sort of separator in the
template, such as a space. It can be used in any mode.
LINE -- reverses the effect of NOLINES if this has been
given previously. (Apologies for the plural/singular
disparity, but it isn't quite the inverse.) It also inserts a
newline into the output at that point; you can use it just for this
if you want an extra blank line between file specifiers.
ZERO -- resets the item and match counters (available for
templates) to zero. Has no other effect on the state.
RESET -- sets the system back to the initialized state:
pattern, template, and tag are cleared, and the
counters are zeroed. Only the internal success flag (that
controls the value returned to AmigaDOS) is left unchanged.
This option is intended for command script use (see below);
you are not likely to need it on a command line.
Two keywords can be used to control input and output channels. Each
takes a single Filename argument (NOT a pattern!):
OUT <File> -- diverts future output to the named file (or
device). Any existing file of that name is deleted.
Any previously selected destination will be closed (except
standard output of course).
OUT - -- (a single dash as the argument) closes any
currently selected output file and restores standard
output (the screen, unless AmigaDOS redirection has also been
used).
WITH <File> -- reads control commands from <File> instead of
the command line. All keywords and argument types
are valid in a script, but NOTHING is reset at the end of a line.
(Don't break a line between a keyword and its argument, though!)
The RESET keyword must be included when you need to clear the
decks. When the end of the script is reached, control returns
to any further arguments on the command line. As with a CLI
command line, anything after a semicolon on a line is ignored:
you may comment your scripts.
+ + + + +
Pattern Matching
________________
The pattern matching algorithm used by Mat is an extension of the
standard file pattern matching scheme used by AmigaDOS. Many people may
not appreciate how general and flexible the method is. It is many times
more capable than the simple "wild-card" matching available on most
personal computers. There are some things that the standard algorithm
doesn't have which would often be useful, and I have done my best to supply
some of these in this extended version.
The discussion that follows may be a fuller exposition of how to use
pattern matching than is available from other sources. If you leave out
references to the "universal-match" character "*", "negation matches", and
"slicing", everything discussed applies just as well to standard AmigaDOS
patterns, which can be used in commands like LIST, DELETE, and COPY.
A pattern is a text string constructed from "plain characters" and
"special characters". It represents a set (possibly a large set) of text
strings that will match it. Remember that it always matches complete
strings; this is not the same as a simple text search, where a match is
signalled if the search string is found anywhere within the source text.
The string being matched by the pattern is always "bounded" in some way,
either because it stands alone -- like a file name -- or because, say, it
is a complete line of text. The newline character at the end is not
usually available to the matching process.
If a pattern argument in a command line contains spaces, it must of
course be enclosed in quotes. There is no way of including quotes in a
pattern which is itself enclosed in quotes, unfortunately, (because of the
way C handles argument strings).
The syntax of the pattern structure is such that complex patterns can
be built from simple ones. Broadly speaking, patterns may be chained end
to end so that successive segments of a complete target string may be
matched by successive segments of the pattern. In addition, each pattern
segment can specify "alternatives": if any of these match, the whole
segment matches.
Plain Characters:
The simplest pattern is a string of plain characters. This will only
match a target string consisting of exactly the same characters in the
same order, which is obviously of limited usefulness. The only case
where you are likely to want this is when getting a particular file
name, and the program is smart enough to go directly to the file in
this case rather than doing a search.
Special Characters:
To build more general patterns we need the special characters. These do
not represent themselves (unless special action is taken): they are
instead structural elements that form the structure of the patterns we
desire. Using them we can build patterns -- or subpatterns -- that will
match, say, any single character, any five characters, any arbitrary
string, or a string that is one of several possible specific
alternatives. We can then put such subpatterns together to end up with
a complete pattern that will match all the various possibilities we are
looking for and no others. The possibilities should become clearer as
we get to specific examples.
The seven special characters used in AmigaDOS file matching are:
' ? | ( ) # and %
To these Mat adds two more:
~ and ^
We'll look at them briefly in order, before we get into a fuller
exploration:
" ' " makes the character following it into a plain character.
" ? " matches ANY single character.
" | " separates alternative patterns.
" ( " and " ) " enclose patterns used in building larger ones.
" # " causes a match to any number of repetitions of the pattern
it precedes.
" % " matches the null string when syntactically necessary.
" ~ " is one way (of two) of sprecifying negation.
" ^ " slices a matched string into segments.
Quoting Characters:
The single quote (" ' ") is used to turn any special character
immediately following it into a plain character. Thus to match against
an actual question mark in a target text you would include the pair
" '? " in the pattern. And of course it can quote itself.
Matching Any Character:
The question mark matches ANY single character. Thus:
???
matches "abc", "xyz", and so on, but not "ab" or "abcd".
Matching Alternatives:
The vertical bar (" | ") separates "alternatives". If any of a set of
patterns separated by bars matches the target, the match is successful.
For example:
abc|def|qwertyuiop
would match any of those three strings, but no others.
The pattern
abc|x?z
would match "abc" or "x" and "z" separated by any single character.
Building Patterns from Others:
The left and right parentheses can be used to enclose a pattern that
you want to match as a unit when it is part of a larger pattern. As one
example we could look for any two characters followed by "abc" or "def"
with the pattern:
??(abc|def)
Combine two or more patterns in sequence this way:
(abc|def)(xxx|yyy)
This will match "abcxxx", "abcyyy", "defxxx", and "defyyy".
Patterns can be nested as far as you like with parentheses:
a(bc|??(xx|yy))d
will match "abcd", or any six-letter group beginning with "a" and
ending in "xxd" or "yyd".
Redundant parentheses do no harm. They may be useful to distinguish
patterns from other constructs.
Pattern Repetition:
The " # " character is always followed by a (sub)pattern. It will match
ANY number of (exact) repetitions of that pattern (INLUDING zero). The
pattern may be a single letter, but if it isn't it must be enclosed in
parentheses. Thus:
#(ab)
matches "ab", "abababab", or simply an empty string. It does not match
"ababa".
Ther pattern to be repeated may be any legal pattern, including more
repetition constructs if you want:
#(ab|?x|#(xy)z)
will match such strings as "abab", "zxab", "qxxyxyxyxyzxyab", and so
on. It will NOT match "abxy".
Matching the Empty String:
The " % " character is used where you have to specify an empty ("null")
string -- normally as one of a number of alternatives. The
construction
(|abc)
is not legal; instead you must use:
(%|abc)
which will match either "abc" or the null string.
Negated Matching:
Mat extends the basic pattern matching syntax by allowing you to
specify patterns that if matched will cause the overall match to fail.
If a negated segment is included in a pattern, and the target string
has ANY POSSIBLE match of the whole pattern that includes that segment,
the match cannot succeed. There are restrictions on negation patterns
not shared by the structures we've talked about up to now; in
particular they can't be nested -- you can't negate a negation --
although they can be inserted at any level in the pattern.
There are two ways of specifying negated patterns. The first will
match ANY string UNLESS it exactly matches the pattern; it is
constructed by prefixing the pattern by the tilde (" ~ "):
ab~(cd)e
will not match "abcde", but will match any other string that begins
with "ab" and ends with "e", such as "abxxxe", "abe", "abce", etc..
The second form is a "negated alternative", indicated by two adjacent
vertical bars (" || "). This is used when, rather than matching ANY
string that is not the negated one, you have a set of patterns you want
to match UNLESS the negated part is also matched. Thus:
a(b?d|?c?||bcd)
will match four character strings such as "abxd", "accc", "abcx", as
long as the whole string is not "abcd".
You can have more than one negated segment, as long as one does not
appear inside another. Thus the following sort of thing is possible
(whether it's also useful though...?):
a~bc~(de)(???||fgh||xyz)
Remember that this will be forced to fail if there is any possible
match that includes a negated section. Thus these will succeed:
acxxx
abbbcddeabc
acdexy
and these will fail:
abcxxx
abbcdexxx
aczxsdefrgthcjxsxcxyz
To stress it once again, a negated match is "aggressive": if there
is ANY possible match that includes a negated section, the whole
match will fail.
Slicing the Matched String:
You can include "slice marks" (the caret -- " ^ ") in your pattern to
select out pieces of the matched string that can be treated individually.
Mat will arrange these "slices" in a manner specified by a template
(next section), to generate desired output.
Once again there is a restriction on the use of this character that
does not apply to the others: only the first four of these marks
encountered during a match will be recorded; any after this will be
ignored. Note that this doesn't mean you can only include a maximum of
four marks; if they are inside alternatives that don't match any part
of the target string, the scan will never encounter them. You should
be sure of what you are doing, though, if you don't want to be
surprised by the program's choices. We'll return to this, and some
other points you should note about the behaviour of slice marks, later.
If there is more than one possible match of the pattern to the target,
the slice will be made at the earliest possible point. Remember this
especially when you have repetitions in your pattern.
Examples:
The pattern #?^x#?
will cut abcdxyz
into abcd xyz
It will also cut abcxxxx
into abc xxxx
The pattern #?^x#?y^#?
will cut abcxxxxyz
into abc xxxxy z
The pattern #?^#x^#?
won't cut much of anything! (because "#x" also matches the null
string.) The first two slices will simply always be empty, and
slice three will contain the whole string.
The pattern #?^(word|another)^#?
will cut "here is another word for you"
into "here is" "another" "word for you"
(using quotes in this case to mark off the slices). Notice that
the cuts are made around "another" rather than "word" because the
earliest match is found.
Slice marks within alternatives can be used, as noted above, but are
tricky. Because of the way the marks are recorded internally, if two
different alternatives containing them match, both marks will be
reported but the position of one of them will be wrong (probably at the
beginning of the string). So it is best to keep the slice marks
outside of any alternation constructions (as shown in the last example
above).
Be careful using negation with slice marks. As noted above, any
match with the negated section causes the whole match to fail: it
does not try to find another match. Therefore you can't use a
negation to force a slice mark to be in a different place. In
general there are some limitations such as these which may prevent
you from cutting up strings exactly the way you want (chopping out
variable spaces can be very awkward for example).
Templates
_________
The Templates Mat uses to generate output lines are basically simple
text strings with "splice-markers" and other "selectors" that indicate
where the pieces of the matched string and other items are to be inserted.
The text segments of a template can be anything you want (except a newline
-- there is a selector for this). A special marker can be used to divide
the template string into "success" and "fail" halves; the "success" part
controls the format of output lines for matches, while the "fail" part will
be output for each input string that doesn't match. Output strings are
always terminated with a newline, unless the NOLINES option is in effect.
You can cancel an existing template by supplying a null string ( "" ). Any
current Tag may be cancelled in the same way. The effect is slightly
different in Directory Search mode: this normally EXPECTS a template to
control the output (and you can't simply omit it), but you can defeat the
requirement by supplying a null template, in which case matches will
produce no output.
Each marker (or selector -- the terms will be used interchangeably) is
a character pair: the caret (" ^ ") followed by a selector character.
Slices from the matched string are numbered -- "^0" to "^4" . Other items
have identifying letters, such as "^N" for line number; the case of these
letters is important (all are currently upper case because you are already
holding down the shift key for the caret). The success/fail divider uses
the vertical bar: "^|".
Not all selectors are valid, or at least have exactly the same meaning,
under all conditions. For example you can't use slices from a matched line
in the "fail" section of a template because -- obviously -- there aren't
any. Then, "line numbers" naturally only apply in text matching, but in
file name matching mode the same selector (^N) keeps track of the number of
files encountered. If you use a selector that is not valid it is simply
skipped over. Of course you can use any selector more than once within a
template.
If a template argument in a command line contains spaces, it must of
course be enclosed in quotes. As with a pattern, you can't include quotes
in a template which is itself enclosed in quotes: use the "^Q" selector
instead. You can include a caret character in the output string (if, for
example you are generating a new Mat command in a script) by the pair "^^".
Slice Selectors:
As four slice marks are allowed in a pattern, there can be a maximum of
five slices of the matched string. These are selected by "^0" for the
piece from the beginning of the string to the first mark, "^1" for the
piece between the first and second, up to "^4" for the remainder of the
string beyond the fourth mark. If there are fewer than four slice
marks, the slice associated with the final existing mark extends to the
end of the string, and all higher-number pieces are empty. Thus if
there are only two marks, "^2" covers the remainder of the string, and
"^3" and "^4" are empty.
For instance, if we use this pattern, with two slice marks:
#?^word ^#?
and this template -- which will omit slice 1:
^0^2
to match and rearrange the string:
"this word will be missing"
we will end up with:
"this will be missing"
Slice marks are only appropriate to match-templates. They are
ignored by 'fail' templates (see below) and in Tags and Labels.
Line Number Selector:
The marker "^N" placed in a template string will insert the current
line Number within the file being scanned at that point into the output
string. It can be used in both "success" and "fail" portions of a
template. In tags and labels it will represent the lines read to that
point. If used in Directory Search or Argument Scanning modes, it
represents the total number of items scanned to that point; it is not
automatically reset in these modes (use ZERO to do so)..
So the pattern #?^(word|another)^#?
and template ^N: ^1
would generate something like 234: another
Index Number Selector:
The pair "^I" inserts an Index number representing a count of matches
so far. The count is kept from the beginning of the program, and is not
reset with a new file (use ZERO to do so). You may use it in the "fail"
section of a template, also in tags and labels, but remember it will
indicate the number of matches, not lines output.
"^I" also works in Directory or Argument Search mode. If no pattern
(aside from the file specifiers themselves) is supplied in these modes,
it will have the same value as "^N", but you can also match the total
set of files found against a Pattern argument, in which case "^I" will
reflect these matches rather than total files.
Original String Selector:
The pair "^O" ("Oh", not "zero" -- I probably should have chosen a
better one...) represents the unsliced Original string. It can be used
in both the "success" and "fail" parts of a template. Thus, to simply
put a line number in front of each matched line, you could use the
template:
^N: ^O
In File Matching mode, this selector is the same as "^F" (below); in
Argument Matching it represents the current argument. It is a null
string for tags and labels in all cases.
Line Break Selector:
The pair "^B" Breaks the output line at that point with a newline
character. For instance, to output line number and slice-1 on one
line, followed by the original string on a new line, you would use:
^N: ^1^B^O
Quote Mark Selector:
It is not usually possible to embed quote marks in template strings
directly, so you can use the selector "^Q" to make them appear at that
point in the output line.
^0 ^Q^1^Q ^2
File Name Selector:
"^F" selects the local name of the current File (i.e without any
directory prefix), in both text and file name matching modes. (Only
in Argument Match is it a null string.)
For example, if you have a filename specifier argument (see later)
:work#?/#?.txt
which has found the file
Work Disk:work_1/sample.txt
the "^F" selector will insert
sample.txt
If the item referenced by the specifier is a Device (such as a PIPE:)
rather than a file, "^F" will return the FULL name as specified
(pattern specifiers will never find devices, anyway). Thus the
specifier:
PIPE:xyz
simply returns:
PIPE:xyz
Warning: if the found object is a directory AND is a root device (e.g.
"DF0" or "DF1:") the Filename is the full name of that disk but WITHOUT
the terminating colon! (but the Full Pathname (below) is correct).
Full Pathname Selector:
"^P" represents the FULL pathname (from the parent device) of the
file. Thus for the immediately preceding example, it would supply:
Work Disk:work_1/sample.txt
Directory Path Selector:
"^D" in a template will insert the full path to the Directory of the
current file. Thus for the above file, ^D would insert:
Work Disk:work_1
If the object found is a Device rather than a file, this is a null
string (but the Full Pathname (^P) will be the same as the Filename
(^F) -- see above). It will also be a null string if the found object
is a directory and the specifier was in the form of a "Device" or
"Parent" reference -- in other words like "xyz:" or "/"; in this case,
the Filename ^F is NOT the full pathname -- just the usual simple name
string.
Literal Caret mark Selector:
"^^" included in a template will generate a single caret mark in the
output.
Failure Template Marker:
A simple template is only applied to strings which have been matched,
and nothing is output when there isn't a match. You can split the
template, however, into two subsections with the special success/fail
division marker "^|". The section preceding this mark is applied for a
successful match just like a simple template; the section following it
is used if the match fails. In the "fail" section, any selectors
desired can be used, except the five slices "^0" - "^4".
A simple use would be to output all lines, whether or not they matched,
but mark or rearrange the matched lines in some way. For example the
following would output them all but put a flag and index number on
each matched line (and corresponding blanks before an umatched one):
MATCH[^I]> ^O^| ^O
A tag may be split with the same "^|" divider, in which case the
success part will be output immediately before the first match as
usual, but the fail part will only appear if there is no match in
the file. (In JOIN mode the behaviour is a little different: both
parts will be output if present, 'success' before, and 'fail' after,
each file.) In addition, the success part may be empty (the tag begins
with the marker); in this particular case, ONLY the fail part will ever
appear -- nothing, not even a newline, is output before the first
match.
This last does not apply to match-templates, where a newline will
be written even when the success part is empty. If you really want no
output on matches, add the NOLINES keyword and place "^B" markers
suitably where you DO want newlines.
File Specifiers
_______________
The arguments in the command line you supply to specify the files that
Mat will examine are really just like those you might give to any AmigaDOS
command, but there are one or two extra features.
For text file searches you will probably most often want to specify a
single file. You do this in the usual way with either the local name of a
file in the same directory, or a path name that includes the chain of
directories needed to reach that file in another. Unlike many other
programs that allow pattern matching in filenames, by the way, Mat is
perfectly happy with specific Device names (non filesystem), such as PIPEs
or the Serial Device.
In place of the simple file name, you can use a pattern to match a group of
files in the same directory. Unlike other AmigaDOS commands this pattern
can employ the extended matching features described above ("*", "~", and
"||"). Slice marks can also be used where they are appropriate (see below).
As is usual in AmigaDOS, case is always ignored when searching for matching
filenames.
You can also use patterns in the directory part of the specification,
in just the same way as in the filename part. (Did you know that you can
also do this in most AmigaDOS commands supporting patterns, such as
DELETE?) All the directories matching that specification will be searched
in turn. However, you cannot split a pattern across directories -- in other
words, a pattern must not include a device or directory separator (":" or
"/"). This means that a given pattern can only match directory names at a
certain "level" in the file hierarchy of the disk. Also you cannot use a
pattern in a device specifier -- these must be simple names. To search
more than one level, or more than one device, you must have more specifier
arguments.
In File Name Search mode, if you don't supply any other pattern, you may
put slice marks in the file name portion of the specifier. You cannot
place them in the directory part. Except in this particular situation
(no main pattern present), the program will ignore slices in the filename.
Examples:
These are valid file specifiers:
myfile.txt
my#?file(.txt|_bak)
df1:work/myfile
:work/myfile
/work/myfile
:(work|old)/my^#?
These are not:
df(0|1):#?/#? -- pattern in device part
df1:/#(work/)myfile -- pattern includes directory separator
:w^#?/my^#? -- slice mark in directory part
+ + + + +
========
Distribution and Copyrights
___________________________
Mat itself and this manual are copyright, but may be freely distributed
without charge. Commercial use is prohibited without the express written
permission of the author.
No fee is asked for the non-commercial use of this program, but if one
day you're feeling generous...
Remarks and Suggestions to:
Peter Goodeve
3012 Deakin Street #D
Berkeley, Calif. 94705
%%%%%%%%%%%%